DialogView

NAME

DESCRIPTION

Creating the Dialog Layout

The layout of a dialog is a VObject tree which is usually referred to as dialog tree or dialog layout and the components of a dialog layout are called dialog items or simply items. The actual layout is up to subclasses which have to override the abstract method DoCreateDialog to create and return the dialog tree. DoCreateDialog is called once when the dialog is opened the first time. The created layout is stored in the instvar dialogRoot.
A dialog layout contains simple, output only items, e.g. the class TextItem and the class ImageItem, items for grouping and aligning of several items such as the class Form, the class Cluster, the class Expander and input sensitive items such as the class ActionButton, class LabeledButton, class ToggleButton, class RadioButton and the class PopupItem. The class OneOfCluster and the class ManyOfCluster are special Clusters implementing a "one of" and "many of" behavior of their contained buttons. The class EditTextItem provides an editable text line; the class NumItem allows to enter a number.
Good examples for creating a dialog layout can be found in the method ChangeDialog::DoCreateDialog, the method FileDialog::DoCreateDialog and the method PrintDialog::DoCreateDialog.

Handling Events from Dialog Items

When creating the dialog layout unique ids must be assigned to all selectable items. When the user selects an item the id of the item is passed to the method Control. Clients that wish to be notified of that event must override Control and check the id. Ids that are not handled should always be passed to the base class.
Predefined ids such as const cIdOk or const cIdCancel are reserved for special items, such as the Ok and Cancel buttons. User defined ids must be greater than const cIdFirstUser.
Examples can be found in the following methods: method ChangeDialog::Control, method FileDialog::Control, method PrintDialog::Control.

Keyboard Focus Management

DialogView overrides the method DispatchEvents and, regardless of the position of the mouse, distributes all keyboard events to the current keyboard focus item (see instvar kbdFocus). If Tab or Shift-Tab is pressed, then the method DoTab is called which assigns the keyboard focus to the next, respectively previous keyboard focus item. An item may also actively grab the keyboard focus, e.g. when the user selects the item with the mouse. DialogView stores all items that are interested in the keyboard focus, in the instvar kbdFocusItems. One of these items is the current keyboard focus item which is additionally referenced by the instvar kbdFocus.
Any kind of VObject may request the keyboard focus, but currently only the class EditTextItem and its subclasses follow this protocol of DialogView. See the method EditTextItem::SetContainer and the method EditTextItem::SendDown for details.
If the user presses the Return key anywhere in the dialog, then the default button (usually the Ok button) is selected. The instvar defaultButton holds the default button and is initialized by a special instance of the class ActionButton when the container chain of the window is set up. See the method ActionButton::SetContainer.
Clients may face a problem if the dialog layout contains an item that does not conform to the keyboard focus protocol of DialogView but should process keyboard events. For example, the dialog tree of a FileDialog contains a CollectionView. On key events it scrolls to the next item whose file name starts with the typed letter. Normally, it would not get any keyboard events, but FileDialog overrides the method DispatchEvents and passes key events explicitly to the CollectionView. See the method FileDialog::DispatchEvents for details.

classes are always derived from DialogView.
class DialogView is never reused directly.
class DialogView is abstract.
class DialogView contains 31 methods.

owner of class:

nobody.

baseclasses:

View

subclasses:

Dialog, TreeView

flags:

ViewFlags

INSTANCE VARIABLES

defaultButton (protected Button *)

refers to the button that is selected when the user presses the Return key. The defaultButton is a special instance of the class ActionButton usually with the label "Ok". When the container chain of the dialog tree is initialized the default ActionButton sets itself as the default button (see method ActionButton::SetContainer). The defaultButton can be accessed with the method GetDefaultButton and is set with the method SetDefaultButton.

dialogRoot (protected VObject *)

is the root of the VObject tree containing the layout of the dialog. It is commonly referred to as dialog tree or dialog layout. When the dialog is opened the first time the dialog tree is created by the method DoCreateDialog. The dialogRoot can be accessed with the method GetRoot and replaced with a new one through the method SetDialog. The whole dialog tree is recursively destroyed in the destructor (by means of FreeAll).

kbdFocus (protected VObject *)

is the dialog item which currently has the keyboard focus (usually an instance of the class EditTextItem). The DialogView passes all keyboard and right mouse button events (for the popup menu) to the kbdFocus. If the Tab is pressed, then the keyboard focus is assigned to another item through the method DoTab. The kbdFocus is always an element of the instvar kbdFocusItems. It can be accessed with the method GetKbdFocus and set with the method SetKbdFocus.

kbdFocusItems (protected OrdCollection *)

contains all dialog items that are interested in getting the keyboard focus. These items are usually instances of the class EditTextItem but may be any kind of VObject. The current keyboard focus item is contained in the instvar kbdFocus. When the user presses Tab or Shift-Tab, then the next, respectively the previous enabled item in this list gets the keyboard focus (see method DoTab). During container initialization of a new dialog tree the dialog items add themselves to this list through the method AddItemWithKbdFocus. See also method EditTextItem::SetContainer.

menu (protected Menu *)

is the popup menu of this dialog. The method GetMenu creates the menu only if there is no next event handler.
Known Problems: The menu is not deleted in the destructor.

modified (protected bool)

indicates whether the layout of the dialog tree has changed. If modified is TRUE, then the layout is recalculated by the method Update next time the dialog is redrawn. By default, the DialogView never sets modified, except in the constructor. The flag modified can be tested with the method IsModified.

INSTANCE METHOD LIST

client interface

AddItemWithKbdFocus
DisableItem
EnableItem
FindItem
GetDefaultButton
GetKbdFocus
GetRoot
IsModified
RemoveItemWithKbdFocus
SetDefaultButton

forwarding

DispatchEvents
DoMenuCommand
Open
SetContainer
SetExtent
SetOrigin

implementation

CalcLayout
DialogView
DoTab
Draw
FindNeighbours
GetMenu
GetMinSize
HasSelection
SetDialog
SetKbdFocus
Update
~DialogView

miscellaneous

Parts

overrider interface

Control
DoCreateDialog

CATEGORIES

Standard Views

FILES

declaration:

Dialog.h

KNOWN PROBLEMS

See instvar menu, method FindItem and method SetDialog.  

HISTORY

Index

NAME

DESCRIPTION

INSTANCE VARIABLES

INSTANCE METHOD LIST

CATEGORIES

FILES

KNOWN PROBLEMS

HISTORY